==============================================================================
AMAZON BSR PREDICTION SYSTEM - CODE DIRECTORY README
==============================================================================

Project: Amazon Best Seller Rank (BSR) Prediction System
Course : CIS Capstone II
Team   : Dylan Suniaga, Anabella (NLP), [TODO: full team roster]
Date   : 2026-04-26

------------------------------------------------------------------------------
DIRECTORY STRUCTURE
------------------------------------------------------------------------------

Code/
├── README.txt                  This file. Explains the directory layout.
├── README.md                   Long-form project overview (markdown).
├── INSTALLATION_GUIDE.md       Step-by-step installation instructions.
├── USER_MANUAL.md              End-user manual for the web application.
├── LICENSE                     Project license.
│
├── source/                     All source code for the project.
│   ├── environment.yml         Conda environment spec (Python 3.10).
│   ├── main.ipynb              Top-level orchestration notebook.
│   ├── .gitignore              Git ignore rules from the source repo.
│   │
│   ├── notebooks/              Research / training pipeline notebooks.
│   │   ├── 00-Data Downloading/      SP-API + ScrapingDog data pulls.
│   │   ├── 01-Base Model with Visuals/  Random-Forest visual baseline.
│   │   ├── 02-Image Analysis/        CV features + XGBoost (cls + reg).
│   │   │     save_models_for_web.py  -> Trains and exports the per-category
│   │   │                                XGBoost models that the backend
│   │   │                                actually serves.
│   │   ├── 03-NLP/                   Text preprocessing and features.
│   │   └── 04-Final Modeling/        Multimodal fusion and stratification.
│   │
│   └── src/                    Production source code.
│       ├── nlp/                Reusable NLP preprocessing utilities.
│       ├── utils/              Shared helpers (data loading, paths, etc).
│       └── web/                Full-stack web application.
│           ├── backend/        FastAPI backend (Python).
│           │   ├── app/        API routes, services, schemas, config.
│           │   │   ├── api/routes.py       All HTTP endpoints under /api.
│           │   │   ├── core/config.py      Settings, categories, features.
│           │   │   ├── services/           Inference, image features,
│           │   │   │                       model registry.
│           │   │   └── models/schemas.py   Pydantic request/response models.
│           │   ├── data/       Pre-built artifacts shipped with backend
│           │   │               (e.g. suggestions.json for UI dropdowns).
│           │   ├── models/     Trained per-category XGBoost models +
│           │   │               PCA transformers, exported for serving.
│           │   └── requirements.txt
│           └── frontend/       Next.js + TypeScript frontend.
│               ├── src/        App Router pages, components, lib, types.
│               ├── package.json
│               ├── next.config.js   Proxies /api/* -> localhost:8000.
│               └── tailwind.config.ts, postcss.config.js, tsconfig.json
│
└── deployable/                 [TODO] Pre-built deployment artifacts:
                                   - frontend production build (.next/ or
                                     `npm run build` output)
                                   - any container images / lockfiles.
                                See INSTALLATION_GUIDE.md for build steps.

------------------------------------------------------------------------------
HOW TO INSTALL AND RUN
------------------------------------------------------------------------------
See INSTALLATION_GUIDE.md (step-by-step with screenshots) and USER_MANUAL.md
in this same directory.

Quick reference (full instructions in INSTALLATION_GUIDE.md):

  Backend:
      conda env create -f source/environment.yml
      conda activate amazon-forecast
      cd source/src/web/backend
      uvicorn app.main:app --reload --port 8000

  Frontend:
      cd source/src/web/frontend
      npm install
      npm run dev          # http://localhost:3000

------------------------------------------------------------------------------
WHAT IS NOT INCLUDED IN THIS DIRECTORY
------------------------------------------------------------------------------
The following large data assets are intentionally excluded (they are
regenerated by the pipeline scripts in source/notebooks/):

  - data/products_with_image_feats.csv  (~4.4 GB combined feature table)
  - data/data_with_scraper.csv          (~60 MB enriched metadata)
  - data/images_amz/                    (~16k product images)
  - frontend/node_modules/              (regenerated by `npm install`)

Trained model artifacts ARE included under
source/src/web/backend/models/ so the web app can run out of the box.

------------------------------------------------------------------------------
DATABASE
------------------------------------------------------------------------------
This project does not use a relational database; all features and trained
models are stored as files (CSV, joblib/pkl, JSON). No SQL dump is required.

==============================================================================
